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Abstract 


This specification updates the iCalendar RELATED-TO property defined in RFC 5545 by adding 
new relation types and introduces new iCalendar properties (LINK, CONCEPT, and REFID) to 
allow better linking and grouping of iCalendar components and related data. 
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1. Introduction 


iCalendar entities defined in [RFC5545] often need to be related to each other or to associated 
metadata. The specifications below support relationships of the following forms: 


Structured iCalendar: iCalendar entities can be related to each other in some structured way, 
for example, as parent, sibling, before, or after. 


Grouped iCalendar: iCalendar entities can be related to each other as a group. CATEGORIES are 
often used for this purpose but are problematic for application developers due to their lack of 
consistency and use as a free-form tag. 


Linked: Entities can be linked to other entities, such as vCards, through a URI and associated 
REL and FMTTYPE parameters. 


1.1. Structured iCalendar Relationships 


The iCalendar [RFC5545] RELATED-TO property has no support for temporal relationships as 
used by project management tools. 


The RELTYPE parameter is extended to take new values defining temporal relationships, a GAP 
parameter is defined to provide lead and lag values, and RELATED-TO is extended to allow URI 
values. These changes allow the RELATED-TO property to define a richer set of relationships 
useful for project management. 


1.2. Grouped iCalendar Relationships 


This specification defines a new REFID property, which allows arbitrary groups of entities to be 
associated with the same key value. 


REFID is used to identify a key allowing the association of components that are all related to the 
referring, aggregating component and the retrieval of components based on this key. For 
example, this may be used to identify the tasks associated with a given project without having to 
communicate the task structure of the project. A further example is the grouping of all sub-tasks 
associated with the delivery of a specific package in a package delivery system. 
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As such, the presence of a REFID property imparts no meaning to the component. It is merely a 
key to allow retrieval. This is distinct from categorization, which, while allowing grouping, also 
adds meaning to the component to which it is attached. 


1.3. Concept Relationships 


The name CONCEPT is used by the Simple Knowledge Organization System, as defined in 
[W3C.REC-skos-reference-20090818]. The term "concept" more accurately defines what we often 
mean by a category. It's not the text string that is important but the meaning attached to it. For 
example, the term "football" can mean very different sports. 


The introduction of CONCEPT allows a more structured approach to categorization, with the 
possibility of namespaced and path-like values. Unlike REFID, the CONCEPT property imparts 
some meaning. It is assumed that the value of this property will reference a well-defined 
category. 


The current CATEGORIES property defined in [RFC5545] is used as a free-form 'tagging' field. 
These values have some meaning to those who apply them but not necessarily to any consumer. 
As such, it is difficult to establish formal relationships between components based on their 
category. 


Rather than attempt to add semantics to the CATEGORIES property, it seems best to continue its 
usage as an informal tag and establish a new CONCEPT property with more constraints. 


1.4. Linked Relationships 


The currently existing iCalendar standard [RFC5545] lacks a general purpose method for 
referencing additional, external information relating to calendar components. 


This document proposes a method for referencing typed external information that can provide 
additional information about an iCalendar component. This new LINK property is closely aligned 
to [RFC8288], which defines the generic concept of Web Linking, as well as its expression in the 
HTTP LINK header field. 


The LINK property defines a typed reference or relation to external metadata or related 
resources. By providing type and format information as parameters, clients and servers are able 
to discover interesting references and make use of them, perhaps for indexing or the 
presentation of interesting links for the user. 


Calendar components are often grouped into collections to represent a calendar or a series of 
tasks, for example, Calendaring Extensions to WebDAV (CalDAV) calendar collections [RFC4791]. 


It is also often necessary to reference calendar components in other collections. For example, a 
VEVENT might refer to a VIODO from which it was derived. The PARENT, SIBLING, and CHILD 
relationships defined for the RELATED-TO property only allow for a unique identifier (UID), 
which is inadequate for many purposes. Allowing other value types for those relationships may 
help but would cause backward-compatibility issues. The LINK property can link components in 
different collections or even on different servers. 
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When publishing events, it is useful to be able to refer back to the source of that information. The 
actual event may have been consumed from a feed or an ics file on a website. A LINK property 
can provide a reference to the originator of the event. 


Beyond the need to relate elements temporally, project management tools often need to be able 
to specify the relationships between the various events and tasks that make up a project. The 
LINK property provides such a mechanism. 


The LINK property MUST NOT be treated as just another attachment. The ATTACH property 
defined in [RFC5545] has been extended by [RFC8607] to handle server-side management and 
stripping of inline data and to provide additional data about the attachment (size, filename, etc.). 


Additionally, clients may choose to handle attachments differently from the LINK property, as 
attachments are often an integral part of the message, for example, the agenda. 


1.5. Caching and Offline Use 


In general, the calendar entity should be self explanatory without the need to download 
referenced metadata, such as a web page. 


However, to facilitate offline display, the link type may identify important pieces of data that 
should be downloaded in advance. 


1.6. Conventions Used in This Document 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 
NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to 
be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in 
all capitals, as shown here. 


The notation used in this memo to (re-)define iCalendar elements is the ABNF notation of 
[RFC5234], as used by [RFC5545]. Any syntax elements shown below that are not explicitly 
defined in this specification come from iCalendar [RFC5545]. 


2. LINK Property Reference Types 


The reference value in the LINK property defined below can take three forms specified by the 
VALUE parameter: 


URI: This is a URI referring to the target. 


UID: This allows for linking within a single collection of calendar components, and the value 
MUST refer to another component within the same collection. 


XML-REFERENCE: In an XML environment, it may be necessary to refer to a fragment of an 
external XML artifact. This value is a URI with an XPointer anchor value. The XPointer is 
defined in [W3C.WD-xptr-xpointer-20021219], and its use as an anchor is defined in 
[W3C.REC-xptr-framework-20030325]. 
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Note that UID references may need updating on import. An example is data to be imported from 
a file containing VTODO and VEVENT components, with a VIODO referring to VEVENT 
components by UID. When imported into a CalDAV system, the VTODO components are typically 
placed in a different collection from the VEVENT components. This would require the UID 
reference to be replaced with a URI. 


3. Link Relation Types 


Two forms of relation types are defined in [RFC8288]: registered and extension. Registered 
relation types are added to the "Link Relations" registry, as specified in Section 2.1.1 of [RFC8288]. 
Extension relation types, defined in Section 2.1.2 of [RFC8288], are specified as unique URIs that 
are not registered in the registry. 


The relation types defined in Section 6.1 will be registered with IANA in accordance with the 
specifications in [RFC8288]. 


4. New Temporal RELTYPE Parameter Values 


This section defines the usual temporal relationships for use with the RELTYPE parameter 
defined in Section 3.2.15 of [RFC5545]: FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or 
STARTTOSTART. 


The [RFC5545] RELATED-TO property with one or more of these temporal relationships will be 
present in the predecessor entity and will refer to the successor entity. 


The GAP parameter (see Section 6.2) specifies the lead (a negative value) or lag (a positive value) 
time between the predecessor and the successor. 


In the description of each temporal relationship below, we refer to Task-A, which contains and 
controls the relationship, and Task-B, which is the target of the relationship. This is indicated by 
the direction of the arrows in the diagrams below. 


Also, each relationship may be modified by the addition of a GAP parameter to the relationship 
that applies to the targeted component. 


RELTYPE=FINISHTOSTART: Task-B cannot start until Task-A finishes. For example, when 
painting is complete, carpet laying can begin. 
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Figure 1: Finish-to-Start Relationship 


RELTYPE=FINISHTOFINISH: Task-B can only be completed after Task-A is finished. The related 
tasks may run in parallel before completion. 


For example, in the development of two related pieces of software (e.g., the API and the 
implementation), the design of the implementation (Task-B) cannot be completed until the 


design of the API (Task-A) has been completed. 


Figure 2: Finish-to-Finish Relationship 


RELTYPE=STARTTOFINISH: The start of Task-A (which occurs after Task-B) controls the finish of 
Task-B. For example, ticket sales (Task-B) end after the game starts (Task-A). 


Figure 3: Start-to-Finish Relationship 


RELTYPE=STARTTOSTART: The start of Task-A triggers the start of Task-B, that is, Task-B can 
start anytime after Task-A starts. 
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Figure 4: Start-to-Start Relationship 


5. Additional New RELTYPE Parameter Values 


This section defines the additional relationships below: 


RELTYPE=FIRST: This indicates that the referenced calendar component is the first in a series 
the referencing calendar component is part of. 


RELTYPE=NEXT: This indicates that the referenced calendar component is the next in a series 
the referencing calendar component is part of. 


RELTYPE=DEPENDS-ON: This indicates that the current calendar component depends on the 
referenced calendar component in some manner. For example, a task may be blocked waiting 
on the other, referenced, task. 


RELTYPE=REFID: This establishes a reference from the current component to components with 
a REFID property that matches the value given in the associated RELATED-TO property. 


RELTYPE=CONCEPT: This establishes a reference from the current component to components 
with a CONCEPT property that matches the value given in the associated RELATED-TO 
property. 


Note that the relationship types of PARENT, CHILD, and SIBLING establish a hierarchical 
relationship. The new types of FIRST and NEXT are an ordering relationship. 


6. New Property Parameters 


6.1. Link Relation 


Parameter name: LINKREL 


Purpose: This property specifies the relationship of data referenced by a LINK property. 
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Format Definition: This parameter is defined by the following notation: 


linkrelparam = "LINKREL" "=" 
(DQUOTE uri DQUOTE 
/ iana-token) ; Other IANA registered type 


Description: This parameter MUST be specified on all LINK properties and define the type of 
reference. This allows programs consuming this data to automatically scan for references 
they support. There is no default relation type. 


Any link relation in the link registry established by [RFC8288], or new link relations, may be 
used. It is expected that link relation types seeing significant usage in calendaring will have 
the calendaring usage described in an RFC. 


LINKREL=latest-version: This identifies the latest version of the event information. 


Registration: These relation types are registered in [RFC8288]. 
6.2. Gap 


Parameter name: GAP 


Purpose: This property specifies the length of the gap, positive or negative, between two 
components with a temporal relationship. 


Format Definition: This parameter is defined by the following notation, where dur-value is 
defined in Section 3.3.6 of [RFC5545]. : 


gapparam = "GAP" "=" dur-value 


Description: This parameter MAY be specified on the RELATED-TO property and defines the 
duration of time between the predecessor and successor in an interval. When positive, it 
defines the lag time between a task and its logical successor. When negative, it defines the 
lead time. 


An example of lag time might be if Task-A is "paint the room" and Task-B is "lay the carpets". 
Then, Task-A may be related to Task-B with RELTYPE=FINISHTOSTART with a gap of 1 day -- 
long enough for the paint to dry. 
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Figure 5: Finish-to-Start Relationship with Lag 


For an example of lead time, in constructing a two-story building, the electrical work must be 
done before painting. However, the painter can move in to the first floor as the electricians 
move upstairs. 


Figure 6: Finish-to-Start Relationship with Lead 


7. New Value Data Types 


This specification defines the following new value types to be used with the VALUE property 
parameter: 


UID: VALUE=UID indicates that the associated value is the UID for a component. 


XML-REFERENCE: VALUE=XML-REFERENCE indicates that the associated value references an 
associated XML artifact and is a URI with an XPointer anchor value. The XPointer is defined in 
[W3C.WD-xptr-xpointer-20021219], and its use as an anchor is defined in [W3C.REC-xptr- 
framework-20030325]. 


8. New Properties 


8.1. Concept 


Property name: CONCEPT 


Purpose: This property defines the formal categories for a calendar component. 
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Value type: URI 
Property Parameters: IANA and non-standard parameters can be specified on this property. 
Conformance: This property can be specified zero or more times in any iCalendar component. 


Description: This property is used to specify formal categories or classifications of the calendar 
component. The values are useful in searching for a calendar component of a particular type 
and category. 


This categorization is distinct from the more informal "tagging" of components provided by 
the existing CATEGORIES property. It is expected that the value of the CONCEPT property will 
reference an external resource that provides information about the categorization. 


In addition, a structured URI value allows for hierarchical categorization of events. 


Possible category resources are the various proprietary systems, for example, the Library of 
Congress, or an open source of categorization data. 


Format Definition: This property is defined by the following notation: 


concept = "CONCEPT" conceptparam ":" 
uri CRLF 
conceptparam = *(";" other-param) 


Example: The following is an example of this property. It points to a server acting as the source 
for the calendar object. 


CONCEPT :https://example.com/event-types/arts/music 


8.2. Link 


Property name: LINK 
Purpose: This property provides a reference to external information related to a component. 
Value type: URI, UID, or XML-REFERENCE 


Property Parameters: The VALUE parameter is required. Non-standard, link relation type, 
format type, label, and language parameters can also be specified on this property. The LABEL 
parameter is defined in [RFC7986]. 


Conformance: This property can be specified zero or more times in any iCalendar component. 


Description: When used in a component, the value of this property points to additional 
information related to the component. For example, it may reference the originating web 
server. 
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Format Definition: This property is defined by the following notation: 


link = "LINK" linkparam ":" 
( uri / ; for VALUE=XML-REFERENCE 
uri / ; for VALUE=URI 
text ) ; for VALUE=UID 


CRLF 
linkparam = (";" "VALUE" "=" ("XML-REFERENCE" / 

KURTH 
UTD } ) 

1*(";" linkrelparam) 

1*(";" fmttypeparam) 

1*(";" labelparam) 

1*(";" languageparam) 

*(";" other-param) 


; the elements herein may appear in any order, 
; and the order is not significant. 


This property is a serialization of the model in [RFC8288], where the link target is carried in 
the property value, the link context is the containing calendar entity, and the link relation 
type and any target attributes are carried in iCalendar property parameters. 


The LINK property parameters map to [RFC8288] attributes as follows: 


LABEL: This parameter maps to the "title" attribute defined in Section 3.4.1 of [RFC8288]. 


LANGUAGE: This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of 
[RFC8288]. 


LINKREL: This parameter maps to the link relation type defined in Section 2.1 of [RFC8288]. 
FMTTYPE: This parameter maps to the "type" attribute defined in Section 3.4.1 of [RFC8288]. 


There is no mapping for "title*", "anchor", "rev", or "media" [RFC8288]. 


Example: The following is an example of this property, which provides a reference to the 
source for the calendar object. 


LINK ; LINKREL=SOURCE ; LABEL=Venue ; VALUE=URT : 
https://example.com/events 


Example: The following is an example of this property, which provides a reference to an entity 
from which this one was derived. The link relation is a vendor-defined value. 


LINK;LINKREL="https://example.com/linkrel/derivedFrom'" ; 
VALUE=URT: 
https://example.com/tasks/01234567-abcd1234.ics 
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Example: The following is an example of this property, which provides a reference to a 
fragment of an XML document. The link relation is a vendor-defined value. 


LINK;LINKREL="https://example.com/linkrel/costStructure" ; 
VALUE=XML-REFERENCE : 
https://example.com/xmlDocs/bidFramework. xml 
#xpointer (descendant: :CostStruc/range-to( 
following: :CostStrucEND[1])) 


8.3. Refid 


Property name: REFID 

Purpose: This property value acts as a key for associated iCalendar entities. 

Value type: TEXT 

Property Parameters: Non-standard parameters can be specified on this property. 
Conformance: This property can be specified zero or more times in any iCalendar component. 


Description: The value of this property is free-form text that creates an identifier for associated 
components. All components that use the same REFID value are associated through that value 
and can be located or retrieved as a group. For example, all of the events in a travel itinerary 
would have the same REFID value, so as to be grouped together. 


Format Definition: This property is defined by the following notation: 
refid = "REFID" refidparam ":" text CRLF 


refidparam = *(";" other-param) 


Example: The following is an example of this property. 


REFID:itinerary-2014-11-17 


9. Updates to RFC 5545 


This specification updates the RELATED-TO property defined in Section 3.8.4.5 of [RFC5545]. The 
contents of Section 9.1 replace that section. 


The RELTYPE parameter is extended to take new values defining temporal relationships, a GAP 
parameter is defined to provide lead and lag values, and RELATED-TO is extended to allow URI 
values. These changes allow the RELATED-TO property to define a richer set of relationships 
useful for project management. 
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9.1. RELATED-TO 


Property name: RELATED-TO 


Purpose: This property is used to represent a relationship or reference between one calendar 
component and another. The definition here extends the definition in Section 3.8.4.5 of 
[RFC5545] by allowing URI or UID values and a GAP parameter. 


Value Type: URI, UID, or TEXT 


Property Parameters: Relationship type, IANA, and non-standard property parameters can be 
specified on this property. 


Conformance: This property MAY be specified in any iCalendar component. 


Description: By default or when VALUE=UID is specified, the property value consists of the 
persistent, globally unique identifier of another calendar component. This value would be 
represented in a calendar component by the UID property. 


By default, the property value points to another calendar component that has a PARENT 
relationship to the referencing object. The RELTYPE property parameter is used to either 
explicitly state the default PARENT relationship type to the referenced calendar component or 
to override the default PARENT relationship type and specify either a CHILD or SIBLING 
relationship or a temporal relationship. 


The PARENT relationship indicates that the calendar component is a subordinate of the 
referenced calendar component. The CHILD relationship indicates that the calendar 
component is a superior of the referenced calendar component. The SIBLING relationship 
indicates that the calendar component is a peer of the referenced calendar component. 


To preserve backwards compatibility, the value type MUST be UID when the PARENT, SIBLING, 
or CHILD relationships are specified. 


The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or STARTTOSTART relationships 
define temporal relationships, as specified in the RELTYPE parameter definition. 


The FIRST and NEXT define ordering relationships between calendar components. 


The DEPENDS-ON relationship indicates that the current calendar component depends on the 
referenced calendar component in some manner. For example, a task may be blocked waiting 
on the other, referenced, task. 


The REFID and CONCEPT relationships establish a reference from the current component to 
the referenced component. 


Changes to a calendar component referenced by this property can have an implicit impact on 
the related calendar component. For example, if a group event changes its start or end date or 
time, then the related, dependent events will need to have their start and end dates and times 
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changed in a corresponding way. Similarly, if a PARENT calendar component is canceled or 
deleted, then there is an implied impact to the related CHILD calendar components. This 
property is intended only to provide information on the relationship of calendar components. 


Deletion of the target component, for example, the target of a FIRST, NEXT, or temporal 
relationship, can result in broken links. 


It is up to the target calendar system to maintain any property implications of these 
relationships. 


Format Definition: This property is defined by the following notation: 


related = "RELATED-TO" relparam ":" 
( text / ; for VALUE=UID 
uri / ; for VALUE=URI 
text ) ; for VALUE=TEXT or default 


CRLF 
relparam = ; the elements herein may appear in any order, 
; and the order is not significant. 
[ LL : " "VALUE" mou ( SUTDA if 
"URI" / 
TEXTA) 


[";" reltypeparam] 
[";" gapparam] 
*(";" other-param) 


Example: The following are examples of this property. 


RELATED-TO:jsmith.part7.19960817T0830900.xyzMail@example .com 
RELATED-TO:19960401-080045-4000F192713-0052@example .com 
RELATED-TO;VALUE=URT ; RELTYPE=STARTTOFINISH: 


https://example.com/caldav/user/jb/cal/ 
19960401-080045-4000F192713.ics 


10. Security Considerations 
All of the security considerations of Section 7 of [RFC5545] apply to this specification. 


Applications using the LINK property need to be aware of the risks entailed in using the URIs 
provided as values. See Section 7 of [RFC3986] for a discussion of the security considerations 
relating to URIs. 


In particular, note Section 7.1 (Reliability and Consistency) of [RFC3986], which points out the 
lack of a stability guarantee for referenced resources. 
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When the value is an XML-REFERENCE type, the targeted data is an XML document or portion 
thereof. Consumers need to be aware of the security issues related to XML processing -- in 
particular, those related to XML entities. See Section 20.6 of [RFC4918]. Additionally, note that the 
reference may be invalid or become so over time. 


The CONCEPT and redefined RELATED-TO properties have the same issues in that values may be 
URIs. 


Extremely large values for the GAP parameter may lead to unexpected behavior. 


11. IANA Considerations 


11.1. iCalendar Property Registrations 


The following iCalendar property names have been added to the iCalendar "Properties" registry 
defined in Section 8.3.2 of [RFC5545]. IANA has also added a reference to this document, where 
the properties originally defined in [RFC5545] have been updated by this document. 


Property Status Reference 
CONCEPT Current Section 8.1 
LINK Current Section 8.2 
REFID Current Section 8.3 


RELATED-TO Current [RFC5545], Section 3.8.4.5; RFC 9253, Section 9.1 
Table 1 


11.2. iCalendar Property Parameter Registrations 


The following iCalendar property parameter names have been added to the iCalendar 
"Parameters" registry defined in Section 8.3.3 of [RFC5545]. 


Parameter Status Reference 

GAP Current Section 6.2 

LINKREL Current Section 6.1 
Table 2 


11.3. iCalendar Value Data Type Registrations 


The following iCalendar property parameter names have been added to the iCalendar "Value 
Data Types" registry defined in Section 8.3.4 of [RFC5545]. 
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Value DataType Status Reference 
XML-REFERENCE Current Section 7 
UID Current Section 7 


Table 3 


11.4. iCalendar RELTYPE Value Registrations 


The following iCalendar "RELTYPE" values have been added to the iCalendar "Relationship 
Types" registry defined in Section 8.3.8 of [RFC5545]. 


Relationship Type Status Reference 
CONCEPT Current Section 5 
DEPENDS-ON Current Section 5 


FINISHTOFINISH Current Section 4 


FINISHTOSTART Current Section 4 

FIRST Current Section 5 

NEXT Current Section 5 

REFID Current Section 5 

STARTTOFINISH Current Section 4 

STARTTOSTART Current Section 4 
Table 4 
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